COMMENT ⊗   VALID 00004 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	Recaux is a package of record auxilaries. They can perform some very nice
C00003 00003	General purpose record handling routines...
C00008 00004	LISP type cells and procedures...
C00013 ENDMK
C⊗;
Recaux is a package of record auxilaries. They can perform some very nice
things for you when you need them. The following file is an annoted list
of them.  This documentation was written at IRCAM in Paris, France in July
1978 by Mark Kahrs (MWK). The original code was written by Russ Taylor
(RHT).  Please address complaints/additions to him. If you have any useful
routines you think might be useful, you might consider getting them
included. Mail a message to MWK if you do.

In order to get the definition file, you must say:

	REQUIRE "sys:recaux.hdr" source!file;

This will get you all of the following definitions:
General purpose record handling routines...

EXTERNAL INTEGER PROCEDURE RECLEN(RPTR(ANY_CLASS) R);
	RecLen gets you the length of the record whose record pointer is R
	The length is of course in words.

EXTERNAL INTEGER PROCEDURE RECTYPE(RPTR(ANY_CLASS) R);
	RecType will return the location of the class of the record whose
	record pointer is R. Note that this means if you want to compare
	classes, you will have to use Location(class) to get the location
	of the class.

EXTERNAL RPTR($CLASS) SIMPLE PROCEDURE $RECTYPE(RPTR(ANY_CLASS) R);
	$RecType returns the record pointer of the class of which R
	is a member.

EXTERNAL INTEGER PROCEDURE FLDTYPE(RPTR(ANY_CLASS) R;INTEGER IX);
	IX is the index of a field of record R. In other words, FldType
	is used to get the type of a field of record R. The field is
	specified by what number it is, starting from 0. The resulting
	type is described in the SAIL manual.

EXTERNAL STRING SIMPLE PROCEDURE CVRCS(RPTR($CLASS) RC);
	CvRCS stands for ConVert Record Class to String. It converts
	a record pointer to a string which is the name of the class
	to which it is an instance.

EXTERNAL STRING SIMPLE PROCEDURE CVRTS(INTEGER RT);
	This is similar to CvRCS except that it takes an integer instead
	of a record pointer.

EXTERNAL INTEGER PROCEDURE FLDREF(RPTR(ANY_CLASS) R;STRING ID);
	This find which index which has the index whose name is ID. In
	other words, this finds the field with name ID in the record
	R.

EXTERNAL RPTR(ANY_CLASS) PROCEDURE BLDNRC(INTEGER RT);
	BuiLD New Record Class. This creates a new record class at runtime.
	It is to be called in the following awkward manner:
		record!pointer (ID) procedure new!id(f1,f2,...,fn);
		return(BldNRC(Location(ID));
	It will create a new instance of record class ID and then copy the
	fields f1,...,fn into the record class. No error checking is done!

EXTERNAL RPTR(ANY_CLASS) PROCEDURE CHKREC(RPTR(ANY_CLASS)R;INTEGER T);
	Given a record pointer and the location of a record class, this
	will check to make sure the record is of the right class.

EXTERNAL RPTR($CLASS) PROCEDURE CLSFND(STRING ID);
	CLasSFiND finds the class whose string is ID. It will return
	a pointer to the $CLASS definition for that class.

EXTERNAL RPTR(ANY_CLASS) PROCEDURE CPYREC(RPTR(ANY_CLASS) R1,R2(NULL_RECORD));
	If R2 is null (or not given), then r1←r2, otherwise a check ismade
	(and how about that!) to make sure r1 and r2 are of identical types
	and then the copy is made.

EXTERNAL PROCEDURE CHGRC(RPTR(ANY_CLASS) RP; INTEGER RC);
	This changes a record to have a record class. Note that the record
	class is the integer address of the class (which is obtained by
	using "location(class)".
LISP type cells and procedures...

The next section of calls were created for a pseudo LISP type calling stuff.
A Cell (as you can see below) is a LISP type CONS cell. 

EXTERNAL RECORD_CLASS CELL(RECORD_POINTER(ANY_CLASS) CAR,CDR);

EXTERNAL RPTR(CELL) PROCEDURE CONS(RPTR(ANY_CLASS) A,D);
	This CONSes A and B as the CAR and CDR of a new cell.

EXTERNAL RPTR(CELL) PROCEDURE APPEND(RPTR(CELL) L1, L2);
	The APPENDs the two lists by doing a RPLACD on the last CDR
	field of L1.

EXTERNAL RPTR(CELL) PROCEDURE LIST2(RPTR(ANY_CLASS) C1,C2);
	LIST2 creates a list of two cells, i.e. (C1 . (C2 . NIL))

EXTERNAL RPTR(ANY_CLASS) RECURSIVE PROCEDURE SECOPY(RPTR(ANY_CLASS) C);
	SeCopy appears to copy the list structure, but then it's not
	real clear.

EXTERNAL BOOLEAN PROCEDURE IN_CL(RPTR(ANY_CLASS) C;RPTR(CELL) L);
	In!Cl searches the list L for the pointer C. If it finds it then
	it returns True, and false otherwise.

EXTERNAL RPTR(ANY_CLASS) PROCEDURE LLOP(REFERENCE RPTR(CELL) C);
	This returns the CAR of a CELL C. But as far as I can tell
	C is not destroyed or mangled in any way like a real Lop.

EXTERNAL RPTR(CELL) PROCEDURE CL_LEN(RPTR(CELL) C);
	Cl!Len returns the length of the list of CELLs, C.

EXTERNAL RPTR(ANY_CLASS) PROCEDURE CONSON(RPTR(ANY_CLASS) X;REFERENCE RPTR(CELL) C);
	ConsOn CONSes C onto the thing X so C is at the end.

An RList is a particular type of list which has pointers to the first and
last elements as well as the total length.

EXTERNAL RECORD_CLASS RLIST(INTEGER LEN;RPTR(CELL) FIRST,LAST);

EXTERNAL PROCEDURE RLADD(RPTR(RLIST) RL;RPTR(ANY_CLASS) REC;INTEGER N);
	This adds a record REC to the RList RL after N cells. If N
	is too large a complaint will be made.

EXTERNAL INTEGER PROCEDURE RLREM(RPTR(RLIST) RL;RPTR(ANY_CLASS) REC;
							INTEGER HOWMANY(1));
	This removes the record REC from the RList RL HOWMANY times.
	Notes that HOWMANY is defaulted to 1, so if called with two
	arguments, it will only get rid of one. It returns the actual
	number it got rid of.

EXTERNAL RPTR(ANY_CLASS) PROCEDURE RLNREM(RPTR(RLIST) RL;INTEGER N);
	This removes the Nth record from the RList RL and returns it.

EXTERNAL INTEGER PROCEDURE RLINX(RPTR(RLIST) RL;RPTR(ANY_CLASS) REC);
	RLINdeX searches the RList RL for the record REC. If it is
	found then a return is immediately made with the number of the
	record. If it isn't found, a 0 is returned.

EXTERNAL RPTR(ANY_CLASS) PROCEDURE RLNTH(RPTR(RLIST) RL;INTEGER N);
	This returns the Nth elemnt of R without destroying anything.

EXTERNAL RPTR(RLIST) PROCEDURE RLCOPY(RPTR(RLIST) RL,RL2(NULL_RECORD));
	RLCopy copies RL into RL2 and returns the copy. This means that
	if RL2 is NULL!RECORD then no store takes place an a copy is made
	of the list.

EXTERNAL MATCHING RECURSIVE PROCEDURE
		MAPRLIST(RPTR(RLIST) RL;REFERENCE RPTR(ANY_CLASS) R);
	A matching procedure is a form of coroutine. Each call will
	CDR down the list until then list is NIL, in which case it
	returns.